home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #1 / Amiga Plus CD - 2000 - No. 1.iso / Tools / Text / Edit / GoldED-Demo / installdata / golded / developer / api / readme
Encoding:
Text File  |  1999-12-03  |  11.9 KB  |  218 lines
  1. CONTENTS
  2.  
  3.   API documentation
  4.  
  5. COPYIGHT
  6.  
  7.   ©1999 Dietmar Eilert. All Rights Reserved.
  8.  
  9.   Dietmar Eilert
  10.   Mies-v-d-Rohe-Str.31, 52074 Aachen, Germany
  11.   Phone: +49-(0)179-5987061 German/English
  12.   E-Mail: Dietmar.Eilert@post.rwth-aachen.de
  13.   E-Mail: dietmar_eilert@yahoo.de (alternative address)
  14.   WWW:    http://members.tripod.com/golded
  15.   Mirror: http://members.xoom.com/golded
  16.  
  17. INTRODUCTION
  18.  
  19.   GoldED  offers  a  fast  interface  for  plug-ins:  the  API  interface  or
  20.   "Application  Programmer  Interface". This interface can be used to add new
  21.   commands to the editor and to implement plug-ins  showing  up  directly  in
  22.   editor windows with their own graphical user interface. It is a synchronous
  23.   library-based interface, ie. plug-ins are shared libraries  loaded  by  the
  24.   host  application (typically GoldED). You must be familiar with the concept
  25.   of programming shared  libraries  -  which  to  some  extent  are  compiler
  26.   specific - if you want to write API plug-ins.
  27.  
  28. HOW TO RUN CLIENTS
  29.  
  30.   Plug-ins  ("API  clients")  are  added  to   GoldED   using   the   plug-in
  31.   configuration  requester.  The  editor  will start all plug-ins associacted
  32.   with a filetype when a text using that filetype  is  loaded.  Plug-ins  are
  33.   started  on  a  per-text  basis. Some plug-ins require startup options (for
  34.   example the name of a configuration file). The startup-options can  be  set
  35.   in the API configuration requester of GoldED: doubleclick on a plug-in name
  36.   to set its command string.
  37.  
  38. INTERFACE DESCRIPTION
  39.  
  40.   It is important to  understand  that  plug-ins  are  libraries.  Libraries,
  41.   (unlike  normal  programs)  have  no  life of their own. They do not "run":
  42.   Libraries are simply a collection of functions. The code in these functions
  43.   is executed only if and when the program using the library starts executing
  44.   them. Plug-in libraries developed for GoldED  are  expected  to  provide  a
  45.   specific  set  of  four  functions  as described in the autodoc file. These
  46.   functions are called by the editor on an as-needed basis, ie.  the  plug-in
  47.   code  does  not  run  parallel  to  GoldED  but  is  executed  directly and
  48.   synchronously by the main editor thread (task). Experienced programmers can
  49.   of  course add asynchronous capabilities by running portions of the plug-in
  50.   code in a second thread.
  51.  
  52. PLUG-IN PROTOCOL
  53.  
  54.   The first function of a plug-in executed by GoldED after  the  plug-in  has
  55.   been  loaded is the APIMountClient() function. This function is expected to
  56.   return a description of the client. The details on  how  this  function  is
  57.   called  by GoldED and what it should return as a result is described in the
  58.   autodoc file. GoldED will use the result of this function - especially  the
  59.   api_Classes  field  -  to  determine if and when the other functions of the
  60.   plug-in   should   be   called.   The   api_Classes   value   returned   by
  61.   APIMountClient()  is  a  mask  field:  It  describes  the event classes the
  62.   plug-in wants to see as input.  For  example,  some  plug-ins  want  to  be
  63.   notified  every  time  the  user  presses  a  key.  These  clients  set the
  64.   API_CLASS_KEY flag in  the  api_Classes  field.  GoldED  will  execute  the
  65.   APIBriefClient()  function  of  the  plug-in every time it detects an event
  66.   matching one of the requested event flags. The plug-in can then do whatever
  67.   it  needs  to  do in its APIBriefClient() function to process the event. It
  68.   must set a return code before it returns control  to  GoldED.  GoldED  will
  69.   continue  to execute the APIBriefClient() function on an as-needed basis as
  70.   events occur until the user closes the text.  At  this  time,  GoldED  will
  71.   execute  the APICloseClient() function of the plug-in before it unloads the
  72.   plug-in so that the plug-in can free local resources.
  73.  
  74. WHAT CAN API CLIENTS DO ?
  75.  
  76.   The APIBriefClient() function of the plug-in is called synchronously by the
  77.   editor. The editor passes information about its internal state as arguments
  78.   to the plug-in when executing this function (see  autodoc.h  for  details).
  79.   The  API  client is free to read all internal configuration details as they
  80.   are exposed by these arguments. This  information  is  guaranteed  to  stay
  81.   valid  during the execution time of the APIBriefClient() function. However,
  82.   all configuration details are  read-only.  API  clients  can  not  directly
  83.   modify the configuration of GoldED with three exceptions:
  84.  
  85.   a) plug-ins can set the cursor to a new position
  86.  
  87.      Plug-ins  may  directly  set  the  cursor  position  in  the  EditConfig
  88.      structure  provided  that  they  set  the  API_REFRESH_SYNC  flag in the
  89.      api_Refresh field returned by APIBriefClient() so that GoldED knows that
  90.      the cursor position has been changed.
  91.  
  92.   b) plug-ins can mark text
  93.  
  94.      Plug-ins may directly change  the  position  of  block  markers  in  the
  95.      EditConfig  structure provided that they set the API_REFRESH_MARKER flag
  96.      in the api_Refresh field returned by  APIBriefClient()  so  that  GoldED
  97.      knows that the marker has been changed.
  98.  
  99.   c) plug-ins can change text
  100.  
  101.      Plug-ins can change  the  text  by  attaching  a  list  of  modification
  102.      "orders"  to  the  api_Order  field  returned by APIBriefClient(). These
  103.      orders contain the new text to be inserted  and  a  description  of  the
  104.      insertion  point.  GoldED  will call the APIFreeClient() function of the
  105.      plug-in after processing the orders so that the plug-in can free  memory
  106.      allocated for the orders.
  107.  
  108. WHAT API CLIENTS MAY NOT DO
  109.  
  110.   All other operations affecting the configuration of GoldED are  unsupported
  111.   by  the  plug-in  interface and require usage of the normal Rexx interface.
  112.   Using the Rexx interface in plug-ins can however be very  tricky:  Remember
  113.   that  the  plug-in  code is executed synchronously: GoldED would be sending
  114.   messages to itself while it is executing plug-in code. That's why  plug-ins
  115.   may   send   asynchronous   rexx  messages  to  GoldED  but  they  may  not
  116.   synchronously Wait() for a reply because  GoldED  can  not  reply  to  rexx
  117.   messages  while  excuting  the  plug-in  code.  Unfortunately, sending rexx
  118.   messages asynchronously does not always make sense (if you need the  result
  119.   code  or  plan  to send a sequence of rexx commands). The best solution for
  120.   this problem is to run portions of the plug-in code, specifically the  rexx
  121.   communication - asynchronously and synchronize this thread with the rest of
  122.   the plug-in code via semaphores or signals.
  123.  
  124. CONTAINER CLIENTS
  125.  
  126.   Plug-ins can request rendering space in editor windows and directly  render
  127.   to  these  areas,  display  buttons, etc. This feature has been inspired by
  128.   ActiveX controls from the Windows world. Embedded plug-ins could be used to
  129.   implement  a  VisualC-style  development  environment, a HEX editor, a HTML
  130.   preview area in editor windows, a class  browser,  visual  feedback  areas,
  131.   virtual shells, toolbars, smart online help systems, etc.
  132.  
  133. IMPLEMENTING CONTAINER CLIENTS
  134.  
  135.   Container  clients  are  implemented  as  normal  API  plug-ins.  The  only
  136.   difference  is that the APIMountClient function - the first function called
  137.   by the host - additionally returns a pointer to an APIArea structure  which
  138.   describes the container (width, height, alignment) requested by the client.
  139.   GoldED automatically overrides the dimensions with the user preferences  if
  140.   the  plug-in  has  been  used before and then continues with allocating the
  141.   container and initializing the output area. Subsequent  notifications  sent
  142.   to  the plug-in (technically speaking calls to the APIBriefClient function)
  143.   contain a pointer to the allocated APIContainer structure  which  describes
  144.   the  container  (position,  rastport,  etc).  One  of  these  calls  is the
  145.   API_ACTION_PAINT notification which is the host's  request  to  redraw  the
  146.   container  contents.  A  few  other  container-related  notifications  help
  147.   clients to cope with window resizing and window refreshing; please see  the
  148.   include files for details.
  149.  
  150. IDCMP MESSAGES AND MESSAGE PORTS
  151.  
  152.   Container clients may allocate their own signals and message ports (e.g.  a
  153.   timer)  and  request IDCMP messages (required for gadget handling) but they
  154.   may not directly Wait() for ports and signals because clients are  libaries
  155.   and  as  such must return control to the program using the libary. Instead,
  156.   they   pass   the   signals   and   the   IDCMP   mask    to    the    host
  157.   (APIClient->api_Signals  and  APIArea->api_IDCMP)  which  will  notify  the
  158.   client if an  event  of  the  specified  type  occurs.  Another  difference
  159.   compared to normal application programming is that due to the fact that all
  160.   plug-ins share the same window, plug-ins are not free to choose gadget  IDs
  161.   freely: the host provides a namespace for gadgets to be used by the plug-in
  162.   (APIContainer->api_Namespace is the first free ID; each client may allocate
  163.   up  to 255 gadgets). Clients may not add gadgets or detach gadgets on their
  164.   own using the normal Intuition functions for the same reason. Instead, they
  165.   have   to  pass  the  gadget  list  as  "order"  of  type  API_ORDER_ATTACH
  166.   respectively API_ORDER_DETACH to the host which will then add  the  gadgets
  167.   to  the  window  or  detach them. These orders usually are sent to the host
  168.   when responding to API_ACTION_ATTACH notifications which is the host's  way
  169.   of telling plug-in that it's time to create gadgets.
  170.  
  171. IDCMP messages
  172.  
  173.   Plug-ins can receive IDCMP messages by setting the corresponding bits (e.g.
  174.   IDCMP_GADGETUP) in APIArea->IDCMP as mentioned in the last paragraph. It is
  175.   important to understand that clients receive all  IDCMP  messages  arriving
  176.   for the host program. For example, clients listening to IDCMP_GADGETUP will
  177.   see these messages not only for their own gadgets but for  all  gadgets  in
  178.   the host's windows. It is the sole responsibility of each plug-in to filter
  179.   out messages meant for the plug-in and to pass all other events back to the
  180.   host  program  (which  will  send  them  to  other  plug-ins before finally
  181.   processing the events on its own). The following IDCMP classes can be used:
  182.  
  183.                 IDCMP_ACTIVEWINDOW    IDCMP_MOUSEBUTTONS
  184.                 IDCMP_CLOSEWINDOW     IDCMP_MOUSEMOVE
  185.                 IDCMP_GADGETDOWN      IDCMP_NEWSIZE
  186.                 IDCMP_GADGETUP        IDCMP_RAWKEY
  187.                 IDCMP_INACTIVEWINDOW  IDCMP_REFRESHWINDOW
  188.                 IDCMP_MENUHELP        IDCMP_SIZEVERIFY
  189.                 IDCMP_MENUPICK        IDCMP_VANILLAKEY
  190.  
  191.   Plug-Ins may not interfere with the host's IDCMP handling. They specificaly
  192.   may  not  modify the window's IDCMP mask nor use the ReportMouse() function
  193.   (to disable or enable IDCMP_MOUSEMOVE  events)  nor  may  they  modify  the
  194.   Window  structure or the windows's Rastport structure. Each client receives
  195.   its own Rastport structure (APIContainer->RPort) to be used for rendering.
  196.  
  197. EXAMPLES
  198.  
  199.   Several example API clients are shipped with GoldED (golded:developer/api).
  200.   Have  a  look  at the provided source code to understand how plug-ins work.
  201.   You may have to adjust the source code before you can  compile  it  because
  202.   the  compilation  of  libraries  is  to  some extend compiler-specific (the
  203.   examples have been developed with DICE).
  204.  
  205. THE FILES
  206.  
  207.   All plug-in related code is  kept  in  the  file  "func.c".  Some  examples
  208.   additonally have initialization code in "init.c" which is executed when the
  209.   library is used for the first time respectively before it is expunged  from
  210.   memory.  You  can use the Init()/Exit() functions in this module for global
  211.   initialization. The other files are mostly library glue code. You can leave
  212.   these files untouched except that you may want to edit the plug-in name for
  213.   you own projects which can be  found  in  "tag.a"  and  of  course  in  the
  214.   makefile  (note  that  you  must use exactly the same name in both files or
  215.   your library will fail to load). You may also want to add code  to  "lib.c"
  216.   to  open  the  shared  libraries  you  need;  most  examples  already  open
  217.   "dos.library", "exec.library" and "intuition.library".
  218.